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1.  INTRODUCTION 


HYDROLIGHT  is  a  radiative  transfer  numerical  model  that  computes  radiance 
distributions  and  derived  quantities  for  natural  water  bodies.  In  brief,  this  model  computes  from 
first  principles  the  time-independent  radiance  distribution  within  and  leaving  any  plane-parallel 
water  body.  Input  to  the  model  consists  of  the  absorbing  and  scattering  properties  of  the  water 
body,  the  nature  of  the  wind-blown  sea  surface  and  of  the  bottom  of  the  water  column,  and  the 
sun  and  sky  radiance  incident  on  the  sea  surface.  Output  consists  both  of  archival  printout  and 
of  files  of  digital  data,  from  which  graphical  or  other  analyses  can  be  performed. 

Version  3.0  of  the  HYDROLIGHT  code  (henceforth  called  H3.0)  was  released  in  March 
1995;  that  code  is  fully  documented  in  Mobley  (1995).  H3.0  is  the  most  general  version  of  the 
HYDROLIGHT  code  and  is  designed  to  give  the  user  great  flexibility  in  specifying  the  details 
of  a  HYDROLIGHT  simulation.  For  example,  output  can  be  requested  at  any  set  of  depths,  in 
order  to  get  increased  depth  resolution  near  features  such  as  microlayers  within  the  water  column; 
the  wavelength  bands  can  be  non-uniform,  in  order  to  get  increased  wavelength  resolution  near 
features  such  as  the  chlorophyll  fluorescence  peak  near  685  nm;  the  water  absorption  and 
scattering  properties  can  be  built  up  from  any  number  of  components;  and  so  on.  However, 
because  of  this  generality,  the  user  must  supply  a  great  deal  of  input  to  H3.0  when  setting  up  a 
computer  run.  This  is  not  an  easy  task,  especially  for  users  who  are  using  H3.0  for  the  first  time 
or  who  are  not  experienced  scientific  programmers.  Moreover,  setting  up  H3.0  requires  that  each 
user  perform  a  number  of  one-time  computer  runs  to  generate  files  of  surface  information  for 
different  wind  speeds  and  of  discretized  phase  functions.  These  files  are  binary  in  order  to 
minimize  their  size  and  read-in  times,  and  therefore  they  cannot  be  ported  from  one  computer 
to  another. 

Experience  has  shown  that  many  users  of  HYDROLIGHT  use  it  in  only  a  simplified  form 
and  do  not  need  its  full  generality.  For  example,  for  remote-sensing  applications  only  the  water¬ 
leaving  radiance  or  the  remote-sensing  reflectance  is  of  interest;  the  light  field  within  the  water 
may  be  of  little  or  no  interest.  Some  users  just  wish  to  make  quick  simulations  at  a  single 
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wavelength,  perhaps  assuming  the  water  to  be  homogeneous  and  using  absorption  and  scattering 
coefficients  read  in  at  run  time  (rather  than  computed  in  a  user-supplied  subroutine).  For  such 
users,  and  for  users  working  with  HYDROLIGHT  for  the  first  time,  convenience  of  running  the 
HYDROLIGHT  model  is  an  important  consideration. 

HYDROLIGHT  version  3.1  (H3.1)  was  developed  with  convenience  as  the  primary  goal. 
Various  options  are  set  to  default  values.  For  example,  the  wavelength  bands  are  taken  to  be 
equal  in  size,  and  in-water  output  is  given  only  at  equally  spaced  depths  between  the  surface  and 
the  depth  of  greatest  interest.  Files  containing  information  about  the  sea  surface  for  various  wind 
speeds  and  files  with  various  discretized  phase  functions  are  now  created  in  ASCII  format.  This 
allows  these  files  to  be  distributed  with  the  H3.1  code,  so  that  users  no  longer  have  to  create  their 
own  versions  of  such  files  (although  they  can  still  do  so  if  they  wish). 

Most  importantly,  a  separate  front-end  program  has  been  written  to  give  users  an 
interactive  interface  for  specifying  an  H3.1  run.  This  interface,  which  is  itself  just  a  Fortran 
program,  asks  the  user  various  questions  about  the  simulation.  These  questions  ask  the  user  to 
pick  a  wind  speed  from  a  list  of  allowed  values,  to  specify  the  solar  angle  and  cloud  cover,  and 
so  on.  Certain  defaults,  such  as  the  wavelength  range  and  bandwidth,  are  displayed  and  the  user 
is  allowed  to  accept  or  change  the  default  values.  Other  defaults,  such  as  the  number  of  depths 
where  output  is  given,  can  be  easily  changed  by  editing  the  front-end  program  code.  Users  can 
therefore  tailor  the  front-end  program  to  fit  their  own  requirements. 

The  front-end  program  uses  the  user’s  responses  to  write  two  files.  The  first  file  is  the 
"input"  file  containing  the  information  (as  described  in  Section  4.2  of  the  H3.0  Users’  Guide) 
required  by  H3.1  to  perform  a  simulation.  The  second  file  is  the  "script"  or  "run"  file  that 
actually  submits  the  H3.1  run  to  the  computer.  This  script  file  attaches  the  appropriate  sea- 
surface  and  phase  function  files,  runs  the  H3.1  code,  and  then  saves  the  output  files  for  later 
examination. 
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2.  OVERVIEW  OF  HYDROLIGHT  3.1 


HYDROLIGHT  Version  3.0  remains  the  general  version  of  the  HYDROLIGHT  code  and 
should  still  be  used  when  the  full  power  of  HYDROLIGHT  is  required.  This  section  describes 
only  the  relatively  minor  changes  made  to  H3.0  code  in  order  to  create  Version  3.1.  The  changes 
to  H3.0  were  purposely  kept  to  a  minimum,  so  that  the  H3.0  Users’  Guide  (Mobley,  1995)  would 
remain  valid  as  the  detailed  reference  for  users  of  H3.1.  The  discussion  here  presumes  that  the 
reader  is  already  somewhat  familiar  with  H3.0,  and  that  the  H3.0  Users’  Guide  is  available  for 
cross-reference. 

2.1  Modifications  to  Part  1 

The  HYDROLIGHT  3.0  Part  1  code  was  changed  in  several  ways.  For  many  users,  it 
will  no  longer  be  necessary  to  run  Part  1,  since  the  needed  output  files  from  Part  1  can  now  be 
distributed  along  with  the  code.  The  modifications  to  Part  1  consist  primarily  of  using  a  standard 
quad  partitioning  scheme,  of  using  azimuthally  isotropic  surface  wave-slope  statistics,  and  of 
writing  the  final  output  files  in  ASCII  format. 

Part  1  of  HYDROLIGHT  computes  the  four  quad-averaged  radiance  transfer  arrays  for 
the  air-water  surface,  using  Monte  Carlo  simulations  as  described  in  Mobley  (1994,  Section  4.7). 
These  computations  require  the  specification  of  a  quad  partitioning  scheme  and  a  wind  speed. 
A  quad  partitioning  divides  the  set  of  all  directions  into  quads,  which  are  cells  defined  by  lines 
of  constant  polar  angle  9  and  constant  azimuthal  angle  (j).  In  H3.1,  a  newly  defined  "standard" 
quad  partitioning  is  used.  This  partitioning  has  a  10-degree  spacing  in  0  and  a  15-degree  spacing 
in  (j),  as  shown  in  Fig.  1.  The  polar  caps  have  a  full  angle  of  10  degrees.  The  centers  of  the 
quads  are  therefore  at  9  =  0,  10,  20,  ...,  80,  and  87.5  degrees.  The  quads  next  to  the  "equator" 
cover  only  five  degrees,  firom  0  =  85  to  90  degrees.  (However,  when  two  five-degree  quads 
adjacent  to  the  equator  are  combined,  this  also  gives  a  10-degree  resolution  for  the  horizontal 
(0  =  90  degree)  radiance,  which  is  not  computed  explicitly.)  This  quad  partitioning  gives 
adequate  angular  resolution  for  most  applications  of  HYDROLIGHT.  (However,  the  other  quad 
partitionings  available  in  H3.0  are  still  available  in  H3.1,  if  users  desire  to  use  them.  The 
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Figure  1,  The  standard  10  by  15  degree  quad  partitioning  used  in  HYDROLIGHT  Version  3.1. 


standard  partitioning  just  described  is  obtained  by  using  M,  N,  iqpart  =  20,  24,  4  in  the  input  to 
Part  1.) 

The  Cox-Munk  capillary  wave-slope  parameters  used  in  H3.0  give  wave-slope  statistics 
that  are  slightly  different  in  the  along-wind  and  cross-wind  directions.  This  is  a  degree  of 
sophistication  in  the  simulations  that  is  irrelevant  to  most  users,  since  the  surface  wave  state  is 
seldom  documented  in  detail.  Therefore,  azimuthally  averaged  slope  statistics  are  used  as  the 
default  in  H3.1.  This  gives  a  surface  that  is  azimuthally  isotropic,  and  consequently  it  is  no 
longer  necessary  for  the  user  to  specify  the  azimuthal  angle  between  the  downwind  direction  and 
the  solar  direction.  (If  desired,  however,  the  anisotropic  slope  statistics  can  still  be  selected  in 
subroutine  inishH.  In  this  case,  the  front-end  program  should  be  modified  to  ask  the  user  for 
the  azimuthal  angle  (j),  as  described  in  the  H3.0  Users’  Guide.) 


The  final  output  file  from  Part  1  is  now  written  in  ASCII  format.  Files  corresponding  to 
wind  speeds  of  C7  =  0,  2,  5,  and  10  m  s’^  are  distributed  with  the  H3.1  code.  These  are  the  wind 
speeds  available  for  selection  when  running  the  front-end  program  and  are  sufficient  for  most 
users.  Users  needing  additional  wind  speeds  can  run  the  H3.1  Part  1  code,  with  the  wind  speed 
being  specified  just  as  described  in  the  H3.0  Users’  Guide,  to  generate  files  for  the  desired  wind 
speeds.  The  front-end  program  can  then  be  modified  to  add  the  new  wind  speeds  to  the  list  of 
allowed  values. 

These  ASCII  files  require  several  times  as  much  storage  as  the  corresponding  binary  files 
created  by  H3.0.  However,  the  ASCII  files  require  less  than  2  MB  each,  which  is  insignificant 
on  most  computer  systems.  (If  desired,  the  output  files  can  still  be  written  in  binary  by  setting 
the  iascii  flag  to  zero  in  the  Part  1  code.  If  storage  is  limited,  the  ASCII  files  also  could  be 
stored  as  compressed  files,  with  only  a  single  file  being  uncompressed  during  a  given  H3.1  run.) 

Finally,  several  internal  files  used  in  Part  1  have  been  made  scratch  files.  These  changes 
are  transparent  to  users  running  Part  1. 

2.2  Modifications  to  Part  2 

Corresponding  modifications  have  been  made  to  H3.0  Part  2  in  order  to  create  H3.1  Part 
2.  First,  of  course,  the  surface  transfer  files  created  by  Part  1  can  now  be  read  either  as  ASCII 
(the  default  for  H3.1)  or  binary  (as  in  H3.0).  Likewise,  when  a  phase  function  is  discretized  by 
running  H3.1  in  "discretization  mode,"  which  is  done  Just  as  described  in  Section  4.1.7  of  the 
H3.0  Users’  Guide,  the  output  file  is  now  written  as  ASCII.  Once  again,  this  means  that 
machine-independent  files  of  phase  function  information  can  be  distributed  with  the  code.  Two 
such  files,  one  for  pure  water  (file  pfpure)  and  one  for  a  typical  particle  phase  function  (file 
pfpart),  are  distributed  with  the  H3.1  code.  These  files  have  the  phase  functions  discretized  for 
the  standard  10  by  15  degree  quad  partition  described  above.  Users  wishing  to  discretize  other 
phase  functions  can  run  H3.1  in  discretization  mode,  just  as  is  done  with  H3.0. 

It  must  be  noted  that  the  abscat  and  phasef  subroutines  described  in  Section  4.1.1  of  the 
H3.0  Users’  Guide  are  still  the  same  in  H3.1.  Thus,  a  user  wishing  to  simulate  a  case  1  water 
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body  with  a  given  chlorophyll  profile  must  still  compile  the  executable  program  for  H3.1  Part 
2  using  the  abscat  routine  found  on  file  abcasel  .f,  and  the  desired  chlorophyll  profile  must  be 
defined  in  subroutine  chiz.  Likewise,  a  user  who  wishes  to  discretize  a  one-term  Henyey- 
Greenstein  phase  function  for  a  given  g  parameter  value  must  define  the  value  of  g  in  the  phasef 
subroutine  given  on  file  pfothg.f,  and  then  make  sure  that  file  pfothg.f  is  compiled  into  the 
executable  program.  The  UNIX  Makefile  that  carries  out  the  compilation  of  the  H3.1  code  is 
almost  identical  to  those  for  H3.0.  The  abscat  and  phasef  subroutines,  Makefiles,  and  related 
issues  are  discussed  in  detail  in  the  H3.0  Users’  Guide, 

The  final  digital  output  file  generated  by  Part  2  contains  the  complete  set  of  information 
about  the  simulation  including,  among  other  things,  the  full  radiance  distribution  at  all  depths  and 
wavelengths  where  output  was  requested.  This  file  is  identical  in  H3.0  and  H3.1  and  is  still 
written  in  binary  form,  which  allows  IDL  (or  other)  plotting  routines  to  read  in  the  H3.1  output 
as  quickly  as  possible  for  interactive  graphical  analysis  of  the  computed  output.  There  is  no  need 
for  the  final  digital  output  files  to  be  ASCII,  since  they  are  usually  discarded  after  graphical 
analysis. 

The  default  printout  (as  opposed  to  the  digital  output)  in  H3.1  has  been  changed  slightly 
to  give  information  that  is  of  greater  interest  in  remote-sending  studies.  For  example,  the  output 
now  includes  the  incident  sky  radiance,  the  surface-reflected  sky  radiance,  the  water-leaving 
radiance,  the  total  upward  radiance,  and  the  remote-sensing  reflectance.  These  quantities  are 
given  as  a  function  of  0,  but  only  in  the  (j)  =  90-degree  plane,  which  is  at  right  angles  to  the  sun’s 
incoming  rays.  This  geometry  corresponds  to  that  usually  used  in  making  remote-sensing 
reflectance  measurements.  This  output  can  be  tailored  to  a  particular  user’s  needs  by  setting 
parameters  in  the  appropriate  printout  routines  in  Part  2  of  the  code  (see,  in  particular,  routines 
readin2  and  pntrad). 

The  default  sky  radiance  model  for  H3.1  is  the  "real  sky"  model  found  on  file  qaraalsky.f 
and  described  in  the  H3.0  Users’  Guide.  Users  wishing  to  use  other  sky  routines  can  load  those 
routines  in  the  Makefile,  and  then  change  the  input  requested  by  the  front-end  program 
accordingly. 
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2.3  Data  files 


The  distributed  H3.1  code  contains  a  directory  named  data,  which  contains  several  ASCII 
files.  The  files  with  names  like  surfwind.5  contain  the  output  from  Part  1  for  different  wind 
speeds.  Here,  for  example,  the  name  surfwind.5  indicates  that  this  file  contains  the  information 
about  the  sea  surface  for  a  wind  speed  of  5  m  s'^.  The  files  named  pfpufG  and  pfpart  contain 
the  discretized  phase  function  for  pure  water  and  for  particles,  respectively.  The  actual  phase 
functions  are  found  on  files  pfpure.f  and  pfpart.f.  The  front-end  program  looks  in  this  directory 
for  the  needed  files.  Therefore,  if  the  user  wishes  to  create  additional  files  for  other  wind  speeds 
or  phase  functions,  they  should  be  given  names  on  the  above  pattern  and  stored  in  this  directory. 

After  an  H3.1  simulation  is  completed,  the  final  binary  file  of  digital  data  is  given  a 
descriptive  name  and  moved  into  directory  data.  The  name  of  this  file  is  created  by  the  front 
end,  using  the  user’s  input. 


3.  THE  FRONT-END  PROGRAM 

The  distinguishing  feature  of  Version  3.1  of  the  HYDROLIGHT  code  is  the  interactive 
front  end.  This  program  is  simply  a  Fortran  program  that  the  user  runs  interactively.  The  user’s 
responses  to  the  questions  asked  by  the  front  end  are  then  used  by  the  front  end  to  write  the  input 
and  script  files  needed  to  run  HYDROLIGHT.  This  front  end  saves  the  user  the  effort  of 
balancing  the  H3.0  Users’  Guide  on  her  knee  while  using  a  text  editor  to  create  the  needed  files. 
File  management  tasks  such  as  attaching  the  Part  1  file  corresponding  to  the  desired  wind  speed 
are  handled  automatically  by  the  front  end.  By  running  the  fi:ont-end  program,  it  is  possible  for 
a  user  who  is  almost  completely  unfamiliar  with  HYDROLIGHT  to  make  a  run. 

The  first  question  asked  by  the  fi-ont  end  is  whether  the  user  wants  the  "standard"  set  of 
questions  or  the  "full"  set.  The  standard  questions  are  designed  to  minimize  the  input  requested 
firom  the  user;  various  parameter  values  not  requested  are  set  to  default  values.  The  full  set  of 
questions  asks  for  more  input,  which  allows  the  user  to  override  the  default  values  and  to  have 
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more  flexibility  in  specifying  the  HYDROLIGHT  run.  For  example,  by  default  in  H3.1,  the  in¬ 
water  printout  is  given  only  at  five  equally  spaced  depths  in  the  water  column.  The  standard 
questions  therefore  do  not  ask  the  user  to  specify  the  depths  were  printout  is  desired.  However, 
the  full  questions  allow  the  user  either  to  accept  the  default  depths  or  to  read  in  a  list  of  depths 
where  printout  is  desired,  just  as  is  done  with  H3.0.  The  defaults  -  in  this  example,  output  at 
five  depths  -  also  can  be  changed  by  resetting  the  appropriate  parameter  values  in  the  front-end 
program.  Thus,  users  can  set  various  defaults  as  desired  for  a  given  series  of  runs,  and  then 
answer  only  the  standard  questions  in  order  to  generate  each  particular  run. 

For  multiple-wavelength  runs,  the  front  end  takes  the  wavelength  bands  to  be  equal,  with 
a  default  value  of  10  nm.  The  default  wavelength  range  covered  is  350  to  700  nm  (the  full  range 
allowed  by  the  HYDROLIGHT  "real  sky"  radiance  model).  Thus  H3.1  computes  the  radiances 
averaged  over  the  35  wavelength  bands  350  to  360,  360  to  370,  ...,  690  to  700  nm.  These  default 
values  can  be  changed  when  the  front-end  program  is  run.  Users  wishing  to  use  unequal 
bandwidths  can  explicitly  enter  the  required  information  into  the  HYDROLIGHT  input  file  after 
the  front-end  program  has  terminated,  the  manner  described  in  the  H3.0  Users’  Guide. 

Other  options,  such  as  the  inclusion  of  bioluminescence  or  inelastic  scattering  in  the 
simulation,  are  set  to  default  values  which  omit  these  effects  from  the  run.  These  defaults  are 
easily  changed,  either  in  the  front-end  program  itself  or  by  requesting  the  full  set  of  questions. 

In  the  distributed  H3.1  code,  the  front-end  program  is  found  on  file  HFE2.f  (for 
HYDROLIGHT  Front  End  for  Part  2)  in  directory  part2,  which  contains  the  code  for  Part  2  of 
HYDROLIGHT.  In  order  to  set  up  and  run  the  front-end  program,  the  user  should  first  edit  file 
HFE2.f  to  set  the  default  path  names  to  values  corresponding  to  where  the  various  H3.1 
directories  are  found  on  the  user’s  computer.  Other  defaults  also  can  be  set  to  the  user’s 
preferences.  After  gaining  some  experience  with  the  front  end,  users  may  wish  to  alter  the 
particular  questions  asked,  which  is  easily  done  by  changing  the  appropriate  statements  in 
HFE2.f. 

After  making  any  changes  to  file  HFE2.f,  it  is  compiled  via  the  command  (on  a  UNIX 
system  running  Fortran  77) 
f77  -o  fe  HFE2.f 
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(The  "-0  f©"  option  simply  names  the  executable  output  file  "fe"  instead  of  the  Fortran  default 
name  "a.out".)  The  front-end  program  is  then  executed  simply  by  entering  the  command 
fe 

and  then  answering  the  questions.  Subsequent  runs  of  the  front-end  program  are  then  made 
simply  by  re-entering  the  "fe"  command;  the  front-end  program  needs  to  be  recompiled  only  if 
further  changes  are  made  to  file  HFE2.f. 

When  the  front-end  program  terminates,  it  tells  the  user  the  name  of  the  script  file  that 
actually  runs  H3.1  (the  exact  script  file  name  is  generated  from  the  user’s  input  to  the  front  end). 
Assuming  for  the  moment  that  the  script  file  name  is  "run. example",  the  user  would  then  enter 
the  command 

run. example  & 

to  submit  the  actual  HYDROLIGHT  run  in  the  background. 

Finally,  it  should  be  noted  that  after  termination  of  the  front-end  program,  the  file  of  input 
information  to  H3.1  (named,  perhaps,  input. example)  is  left  as  an  ASCII  file  in  the  part2 
directory.  Before  submitting  the  H3.1  run,  the  user  can,  if  desired,  edit  this  input  file  to  make 
any  desired  changes  in  the  specification  of  the  run  to  be  made. 
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